Crate winsafe[−][src]

Expand description

Win32 GUI and related APIs in safe, idiomatic Rust.

WinSafe has:

high-level structs to build native Win32 GUI applications;
low-level Win32 API constants, functions and structs related to GUI.

If you’re looking for a comprehensive Win32 coverage, take a look at winapi or windows crates, which are unsafe, but have everything.

Links:

Crate – crates.io/crates/winsafe;
GitHub – github.com/rodrigocfd/winsafe;
examples – github.com/rodrigocfd/winsafe-examples.

Usage

Add the dependency in your Cargo.toml:

[dependencies]
winsafe = "0.0.6"

To enable the DirectShow COM module, use:

[dependencies]
winsafe = { version = "0.0.6", features = ["dshow"] }

To enable the Shell COM module, use:

[dependencies]
winsafe = { version = "0.0.6", features = ["shell"] }

Modules overview

The Win32 bindings are divided into a few modules:

root – the root of the crate has Win32 free functions and structs;
co – types and values of Win32 constants;
msg – window messages;
gui – high-level GUI wrappers.

And additionally:

dshow – Win32 DirectShow COM interfaces;
shell – Win32 Shell COM interfaces.

The GUI API

WinSafe features idiomatic bindings for the Win32 API, but on top of that, it features a set of high-level GUI structs, which scaffolds the boilerplate needed to build native Win32 GUI applications, event-oriented. Unless you’re doing something really specific, these high-level wrappers are highly recommended – you’ll usually start with the WindowMain.

One of the greatest strenghts of the GUI API is supporting the use of resource files, which can be created with a WYSIWYG resource editor.

GUI structs can be found in module gui.

Native function calls

The best way to understand the idea behind WinSafe bindings is comparing them to the correspondent C code.

For example, take the following C code:

HWND hwnd = GetDesktopWindow();
SetFocus(hwnd);

This is equivalent to:

use winsafe::HWND;

let hwnd = HWND::GetDesktopWindow();
hwnd.SetFocus();

Note how GetDesktopWindow is a static method of HWND, and SetFocus is an instance method called directly upon hwnd. All native handles (HWND, HDC, HINSTANCE, etc.) are structs, thus:

native Win32 functions that return a handle are static methods in WinSafe;
native Win32 functions whose first parameter is a handle are instance methods.

Now this C code:

PostQuitMessage(0);

Is equivalent to:

use winsafe::PostQuitMessage;

PostQuitMessage(0);

Since PostQuitMessage is a free function, it’s simply at the root of the crate.

Native constants

All native Win32 constants can be found in the co module. They’re all typed, what means that different constant types cannot be mixed (unless you explicitly say so).

Technically, each constant type is simply a newtype with a couple implementations, including those allowing bitflag operations. Also, all constant values can be converted to its underlying integer type.

The name of the constant type is often its prefix. For example, constants of MessageBox function, like MB_OKCANCEL, belong to a type called MB.

For example, take the following C code:

let hwnd = GetDesktopWindow();
MessageBox(hwnd, "Hello, world", "My hello", MB_OKCANCEL | MB_ICONINFORMATION);

This is equivalent to:

use winsafe::{co::MB, HWND};

let hwnd = HWND::GetDesktopWindow();
hwnd.MessageBox("Hello, world", "Title", MB::OKCANCEL | MB::ICONINFORMATION)?;

The method MessageBox, like all native functions that can return errors, will return WinResult, which can contain an ERROR constant.

Native structs

WinSafe implements native Win32 structs in a very restricted way. First off, fields which control the size of the struct – often named cbSize – are private and automatically set when the struct is instantiated.

Pointer fields are also private, and they can be set and retrieved only through getter and setter methods. In particular, when setting a string pointer field, you need to pass a reference to a WString buffer, which will keep the actual string contents.

For example, the following C code:

WNDCLASSEX wcx = {0};
wcx.cbSize = sizeof(WNDCLASSEX);
wcx.lpszClassName = "MY_WINDOW";

if (RegisterClassEx(&wcx) == 0) {
    DWORD err = GetLastError();
    // handle error...
}

Is equivalent to:

use winsafe::{RegisterClassEx, WNDCLASSEX, WString};

let buf = WString::from_str("MY_WINDOW");

let mut wcx = WNDCLASSEX::default();
wcx.set_lpszClassName(&buf);

if let Err(err) = RegisterClassEx(&wcx) {
    // handle error...
}

Note how you don’t need to call GetLastError to retrieve the error code: it’s returned by the method itself in the WinResult.

Text encoding

Windows natively uses Unicode UTF-16.

WinSafe uses Unicode UTF-16 internally but exposes idiomatic UTF-8, performing conversions automatically when needed, so you don’t have to worry about OsString or any low-level conversion.

However, there are cases where a string conversion is still needed, like when dealing with native Win32 structs. In such cases, you can use the WString struct, which is also capable of working as a buffer to receive text from Win32 calls.

Modules

co

Win32 constants and types of constants.

dshow

DirectShow COM interfaces, structs and constants.

gui

High-level GUI abstractions for user windows and native controls. They can be created programmatically or by loading resources from a .res file. These files can be created with a WYSIWYG resource editor.